README.TXT for /pub/mae/product-trial/3.0 r5: 07-Mar-97 RELEASE NOTES FOR MACINTOSH APPLICATION ENVIRONMENT 3.0 UPDATE 3 07 March 1997 ===================================================================== ABOUT THIS DOCUMENT ===================================================================== REVIEW THIS DOCUMENT CAREFULLY BEFORE INSTALLING OR USING MAE 3.0! This document is a "road map" to the other MAE documentation as well as the MAE installation process. Included are useful tips and cautions regarding installation of the product. Information contained in this document may have changed since its inclusion with the MAE 3.0 product materials. For the latest information on MAE, you are strongly encouraged to visit the MAE web site at http://www.mae.apple.com/ You may wish to bookmark this URL for future reference. We also suggest that you keep a printed copy of this document with your MAE 3.0 product materials. Note that for simplicity's sake, we refer to MAE 3.0 Update 3 as MAE 3.0 throughout this document. ===================================================================== SUPPORTED WORKSTATIONS AND OPERATING SYSTEMS ===================================================================== MAE 3.0 has been thoroughly tested on Sun SPARC workstations running Solaris 2.5 and HP series 700 workstations running HP-UX 9.0.5 and HP-UX 10.10. MAE is also compatible with other final release versions of Solaris (2.4 and later) as well as HP-UX (9.0.3 and later) with the exception of HP-UX 10.01. In the event that you have installed HP-UX 10.01, you must first upgrade to HP-UX 10.10 (or later) if you wish to use MAE 3.0. ROSS HyperSPARC processors are supported in this release. You are encouraged to verify that you have the latest patches from ROSS Technology; they maintain a web site at http://www.ross.com/. A minimum of 32MB of memory must be available on the workstation; we recommend 48MB for optimal performance. ===================================================================== WHAT'S NEW IN MAE 3.0 ===================================================================== ** NEW LICENSING PROCEDURE You must obtain a license key before you can use MAE 3.0. - If you have purchased the product, review the documents `About MAE 3.0 License Keys' and `MAE 3.0 License Registration'. These documents are included as `LIC_REG.TXT' in the top level directory of the MAE 3.0 CD-ROM as well as in hardcopy form as part of your MAE product materials. - If you will be using the MAE 3.0 Free Demo, you must obtain a key from the MAE web site at http://www.mae.apple.com/ For more information on license management, refer to the Appendix of the ADMINISTRATOR'S MANUAL, "The License Manager". Note that the `License Binder' keys from earlier versions of MAE cannot be used with MAE 3.0. ** NEW FEATURES AND ENHANCEMENTS FOR MAE 3.0 For a list of new features and product enhancements that we have incorporated into MAE 3.0, refer to the Frequently-Asked Questions (FAQ) available from the MAE web site. ** KNOWN ISSUES FOR MAE 3.0 We strongly encourage you to examine the current list of unresolved issues that have been identified for this release of MAE 3.0. Whenever possible, a workaround or other comment has been included with each issue. An up-to-date version is maintained on the MAE web site. ** UPGRADING FROM PREVIOUS VERSIONS OF MAE MAE 3.0 can update existing installations of MAE 2.0.x; it is not possible to upgrade from MAE 1.0. Review the section titled "RUNNING MAE FOR THE FIRST TIME AFTER INSTALLATION" (later in this document) for details on upgrading your workstation to MAE 3.0. ===================================================================== DOCUMENTATION FOR MAE 3.0 ===================================================================== Documentation for MAE 3.0 is supplied as PDF (Adobe Acrobat) files which can be read from both Unix and from within MAE. You will need to install the Adobe Acrobat Reader in order to view the MAE 3.0 documents: - USER'S MANUAL, "Macintosh Application Environment User's Manual" - ADMINISTRATOR'S MANUAL, "Macintosh Application Environment System Administrator's Manual" These manuals are supplied as `USER.PDF' and `ADMIN.PDF' in the `/DOCS' directory of the MAE 3.0 CD-ROM. To install Acrobat Reader for HP-UX, execute the shell script `INSTALL' found on the MAE 3.0 CD-ROM in the directory `/DOCS/HPUX/'. For Solaris, use `/DOCS/SOLARIS/'. The documents are also available for free from the MAE web site. Additionally, the manuals and Acrobat Reader are installed into the `docs' subdirectory of `Apple Extras' (located in the Apple directory) during an `Easy' install or if explicitly selected during a `Custom' install. An alias to the `docs' directory is located in the `Apple Extras' folder for each MAE user. To install the Acrobat Reader for Macintosh, simply double-click on its installer file. ===================================================================== OTHER MAE 3.0 INFORMATION RESOURCES ===================================================================== ** THIS README FILE This document contains important notes on this version of MAE 3.0 and its related documentation. Review this document carefully before installing or using MAE 3.0; it is included as README.TXT on the MAE 3.0 CD-ROM. For your convenience, a copy is also maintained on the MAE web site. ** MAE-USERS MAILING LIST The MAE Engineering Team has created an unmoderated mailing list named `mae-users' that encourages informal discussion of the MAE product. `mae-users' permits our customers to assist each other and distribute hints and other information about the product. Although the MAE Engineering Team monitors all submissions, we generally do not respond. As appropriate, we may include fixes in a future patch and/or update our documentation suite (including our web site). Announcements regarding patch availability are made on our mailing lists as well as on our web site. For more information on `mae-users', send a message with the body text `info mae-users' (without the quotes) to `listproc@solutions.apple.com'. ** THE MAE WEB SITE The MAE Engineering Team maintains up-to-date information on the MAE 3.0 product. We urge you to regularly check the web site for the latest news on known issues, patches, and bug fixes as well as other helpful hints and tips. The following resources are available: ** Frequently-Asked Questions (FAQ) ** Known issues and workarounds ** Updates to the MAE documentation (PDF files) ** Bug reporting ** Feedback facilities ** HyperMail archive of the `mae-users' mailing list Access to all of these resources is via the MAE web site at http://www.mae.apple.com/ ===================================================================== HOW TO PROCEED ===================================================================== Before installing MAE 3.0, read (1) this document, (2) Chapter 1 of the USER'S MANUAL, "Installing the Macintosh Application Environment", and (3) the web-based resources for current status on known issues and workarounds. After completing your installation of MAE, you will find the information on the MAE web server useful for solving commonly-encountered situations. ===================================================================== INSTALLING AND RUNNING MAE 3.0 ===================================================================== The remainder of this document is functionally organized as follows: I. VERIFYING VENDOR PATCHES IN YOUR WORKSTATION SOFTWARE II. INSTALLING STREAMS/UX (HP-UX 9.0.X only) III. RUNNING THE MAE INSTALLER IV. RUNNING MAE FOR THE FIRST TIME AFTER INSTALLATION Items applicable only to Sun workstations are labeled "(Sun only)"; those applicable only to HP workstations are labeled "(HP only)". All other items apply to both workstation types. I. VERIFYING VENDOR PATCHES IN YOUR WORKSTATION SOFTWARE ========================================================= MAE was tested against the OS versions and patch levels as listed below for all environments (Solaris and HP-UX). Installation of any other OS patches (beyond those listed here) is at the sole discretion of the customer. Apple Computer, Inc. and the MAE Engineering Team make no recommendations regarding the administration and maintenance of workstations on which the MAE product is installed. You are strongly urged to verify the latest patch revisions and recommendations with the respective workstation OS vendors. - Solaris v2.4 with Sun's Recommended Patch Cluster. - Solaris v2.5 with Sun's Recommended Patch Cluster. UltraSPARC workstations with Creator 3D cards additionally require 103076-08. - Solaris v2.5.1 with Sun's Recommended Patch Cluster. UltraSPARC workstations with Creator 3D cards additionally require 103796-03. - HP-UX 9.0.x with the following patches: PHKL_9229, PHKL_9868, PHNE_9100, PHSS_4341. HP-UX 9.0.x workstations with FDDI also require one of the following patches, depending upon the FDDI hardware present in your workstation: PHNE_4717 (built-in FDDI), PHNE_4003 (EISA FDDI). - HP-UX 10.10 with no additional patches. - HP-UX 10.20 with no additional patches. For further information on OS patches for your workstation, contact your system administrator as well as your authorized Sun or HP support organizations. Both vendors maintain web sites that distribute patches and up-to-date information; you may require a support contract in order to gain full access to these resources. For HP-UX information: http://support.mayfield.hp.com For Solaris information: http://sunsolve.sun.com II. INSTALLING STREAMS/UX (HP-UX 9.0.x only) ============================================ The STREAMS package is required for MAE to function with HP-UX 9.0.x; it is not required for HP-UX 10.x. The STREAMS filesets are supplied on the CD in a `tar' file in the directory `/STREAMS'. Do not attempt to un-tar this file; the /etc/update program understands how to read the tar format. Two STREAMS packages are included: 3STREAMS.TAR and 5STREAMS.TAR. You should install 3STREAMS.TAR on HP-UX 9.0.3 and 5STREAMS.TAR on HP-UX 9.0.5 or 9.0.7. The following filesets are included: STREAMS STREAMS-DLPI STREAMS-MAN TLI-XTI-MAN To install STREAMS: - mount the CD-ROM on your workstation - install all four filesets by using the /etc/update command. WARNING: installing STREAMS will reboot your workstation. In the following example, it is assumed that the MAE CD-ROM was mounted at `/cdrom': /etc/update -rs /cdrom/STREAMS/3STREAMS.TAR '*' -or- /etc/update -rs /cdrom/STREAMS/5STREAMS.TAR '*' III. RUNNING THE MAE 3.0 INSTALLER =================================== ** Read Chapter 1 of the USER'S MANUAL, "Installing the Macintosh Application Environment" before running the MAE Installer. ** BACK UP ALL IMPORTANT FILES ON YOUR WORKSTATION! If you have a previous MAE installation, be sure to back up or rename your MAE files. This includes resources for each user (System Folder, .mac, and any additional directories such as `Apple Extras') as well as the Apple directory (appledir). IMPORTANT: some UNIX backup utilities are not compatible with Macintosh file names, which contain spaces and 8-bit special characters. Ensure that your backup utility will handle these conditions before proceeding. ** The most straightforward way to install MAE is to run the Installer while logged onto your workstation as `root'. If you run as an ordinary user, it will not be possible to install system-level facilities such as the AppleTalk kernel modules. ** If you choose an `Easy' install or select the AppleTalk package as part of a `Custom' installation, MAE 3.0 AppleTalk resources will be installed on your workstation. If a previous version of MAE AppleTalk resources exist, they will be updated. The MAE 3.0 AppleTalk resources will work with your existing MAE 2.0.x installations, but note that the reverse is NOT true (i.e., MAE v2.0.x AppleTalk is not compatible with MAE 3.0). As a precaution, we suggest that you copy the files that will be updated by the Installer to a safe place prior to installing MAE 3.0. The names of the files are as follows: - For HP-UX 9.0.x, it is the kernel itself: /hp-ux - For HP-UX 10.x, it is the kernel itself: /stand/vmunix - For Solaris, the AppleTalk components are comprised of several files: /kernel/strmod/adsp /kernel/strmod/at_atp /kernel/strmod/at_sig /usr/kernel/drv/atalk ** (HP only) The Installer will not install MAE 3.0 on HP-UX 10.01. You must upgrade to HP-UX 10.10 or later BEFORE installing MAE 3.0. ** The Installer will upgrade your existing appledir to version 3.0 resources. The installer archives your existing appledir during the MAE installation process, but removes the archived files upon successful completion of the installation. ** A new directory named `/man' will be created in the Apple directory for the man (manual) pages. It contains the `man1' and `man1m' pages for MAE 3.0. For more information on the man pages, see Chapter 2 of the USER'S MANUAL, "Starting and Quitting MAE". ** IMPORTANT: The MAE binaries for HP-UX 9.0.x, HP-UX 10.x and Solaris are not interchangeable. If you have more than one type of system at your site, ensure that you run the Installer for each OS. The MAE Installer must be run on the same OS that you are trying to install for (e.g., you cannot run the Installer on Solaris to extract binaries for HP-UX). ** You may experience problems when attempting to install MAE on an AFS volume. MAE cannot be installed on an AFS volume at all unless the installing user is the super user and has AFS administration privileges. Possible workarounds for residual difficulties: (1) upgrade to the latest release of AFS, which supports 8-bit characters in file names (2) install MAE onto a local or NFS-mounted volume and then copy the MAE Apple directory (appledir) onto your AFS volume. (Remember: if you move the appledir, you must use the `-appledir' command line option to start MAE.) ** (Sun only): During installation of MAE 3.0 into an AFS file system, very long AFS pathnames or very large AFS volumes may cause the Installer to fail. The Installer parses the output from the command `df -k'; the failure condition occurs when the pathname or volume size fields run together without an intervening space. Before executing the Installer, execute a `df -k' command to verify that these two fields are properly separated by at least one space. ** (HP only) If you are running automounter and install MAE 3.0 into an automounted directory, specify the path in /tmp_mnt rather than /net (e.g. `/tmp_mnt/net/lukas/apple' instead of `/net/lukas/apple'). ** When running the Installer, do not use destination directory names ending in special characters such as +, -, or &. ** Customizing the Install process for mass installation: Some sites have installed MAE on a central NFS or AFS server. Before undertaking support of such an installation, read Chapter 2 of the ADMINISTRATOR'S MANUAL, "Customizing MAE and Your Workstation". You should also review the configuration and contents of the file `/etc/mae_fileshare' which can be used to limit access to files via MAE Filesharing. For more information, read Chapter 5 of the ADMINISTRATOR'S MANUAL, "AppleTalk Administration". IV. RUNNING MAE FOR THE FIRST TIME AFTER INSTALLATION ====================================================== ** Read Chapter 2 of the USER'S MANUAL, "Starting and Quitting MAE" before running MAE 3.0 for the first time. ** Before you can run MAE successfully, you must configure license management for MAE. Refer to the document `MAE 3.0 License Registration', which is included as `LIC_REG.TXT' in the top level directory of the CD-ROM as well as with your product distribution package in hardcopy form. For more information on license management, refer to the Appendix of the ADMINISTRATOR'S MANUAL, "The License Manager". ** When MAE 3.0 is launched for the first time and encounters a System Folder from MAE 2.0.x, it automatically updates the System Folder resources to MAE 3.0. Only the Macintosh OS resources that are required by MAE will be changed; third party resources (e.g., user-installed extensions) will not be affected. Note that a backup copy of these files will not be made; you should make a copy of your System Folder and .mac directory before running a new version of MAE. In the unlikely event that you have trouble running MAE after the System Folder update occurs, follow this procedure: - quit MAE (Shutdown) - rename your System Folder and `.mac' directory; for example: mv System\ Folder old.system.folder mv .mac old.mac - relaunch MAE to create a new System Folder and `.mac' directory. - if you need Extensions or other files from the renamed System Folder, copy them to the new System Folder one at a time, restarting MAE after each new file is added to verify correct operation. Note that as a result of using MAE 3.0, several new directories will be added to your existing .mac directory. ** The first time MAE is launched for a new user, the following directories will be created: System Folder .mac Apple Extras Both the `System Folder' and `.mac' directories are required for MAE and will be placed by default in each user's home directory. You can change the location of these two directories by using the `-sysfol' and `-macdir' command line options; see Appendix C of the USER'S MANUAL, "Command Options and X Resources" for more information on command line options. The `Apple Extras' folder contains aliases to useful Macintosh utilities and other resources. It replaces the `demos', `Tools', and `man1' aliases that were created as part of MAE 2.0. The following resources are placed in the `Apple Extras' folder: - AppleScript 1.1 - HyperCard Player 2.3.5 - MoviePlayer 2.5 - OpenDoc 1.1 Installer/CyberDog 1.1 Installer - SimpleText 1.3.1 - Shareware/freeware, located in the folder `Third Party': - Disinfectant 3.6 - Stuffit Expander 4.0.1 - DropStuff w/EE 4.0 - Fetch 3.0.1 Ensure that you read the document `Disclaimer-Please Read' before using any of the shareware/freeware applications. We ask that you honor any shareware fees, as appropriate. ** If you choose to install MAE 3.0 into the same home directory as an existing MAE 2.0.x installation, some of the 2.0.x aliases may point to resources that are not present or were changed in 3.0. This is particularly true if you subsequently remove your Apple directory (appledir) for 2.0.x. Example: the aliases for `tools' points to resources in the 2.0.x appledir that are in different locations in 3.0. Similarly, if the `Apple Extras' folder exists from a previous version of MAE, the aliases in it may no longer function properly after installing MAE 3.0. You should rename the `Apple Extras' folder before executing MAE 3.0 for the first time. ** If you wish to move items from previous installations of MAE (2.0.x) from saved System Folders to MAE 3.0: - Some aliases may no longer work; if so, they will need to be recreated. - Some applications (e.g., Microsoft Office) store information within the product itself that contains the path to the directory into which it was originally installed. Therefore, you may need to reinstall these applications. ** With the exception of `.MIV_file', do not delete or change any of the files or folders located in the `.mac' directory for each MAE user. You may irrecoverably damage your installation of MAE if you attempt to do so. More information on `.MIV_file' can be found in Chapter 2 of the ADMINISTRATOR'S MANUAL, "Customizing MAE and Your Workstation". ** Do not manually create a MIV specifically for any of the three critical directories needed by MAE to function: (1) .mac, (2) System Folder, and (3) Apple directory (appledir). If these directories are not contained within one of the startup MIVs (i.e., via an entry in the .MIV_file located in each user's .mac directory), MAE automatically creates a MIV of the parent directory containing the critical resource. Example: if the appledir is `/opt/apple' and `/' is not a startup MIV, then `/opt' will automatically be created as a MIV. Problems can arise if a MIV entry is created directly for one of the critical directories named above (or one of their subdirectories) rather than contained in a parent MIV. The MacOS does not expect the System Folder to be a volume (as opposed to a folder within a volume). Similarly, having `/opt/apple' be a volume (rather than `/opt') may also cause problems. ** If you are upgrading from MAE 2.0.x, the following section will be useful in retaining association of documents with their creator applications in MAE 3.0. We suggest that you review it carefully before running MAE 3.0 for the first time. If you prefer not to perform the steps outlined below, your documents will be associated with their creator applications gradually (as you access the applications in the Finder). In MAE 2.0.x, the entire filesystem for your workstation environment was shown on the Finder Desktop as a disk named `/'. This has changed for MAE 3.0. By default, you will now see: - a disk representing your home directory - a disk that contains your Apple directory (appledir) If you wish to see other directories represented on the Desktop (beyond the defaults listed above), you will need to create a static MIV entry in your `.MIV_file. For more information on MIVs, review Chapter 2 of the ADMINISTRATOR'S MANUAL, "Customizing MAE and Your Workstation". If you make any changes to the `.MIV_file', you should also rebuild your Desktop (as detailed in the next paragraph). Similarly, Desktop rebuilds may have been problematic in MAE 2.0 since (in some cases) the entire volume `/' was being searched. (A rebuild is performed the very first time MAE is launched for a new user or if specifically requested with the `-rebuild' command line option.) With MAE 3.0, the default behavior is to search only the appledir during a rebuild. In order to retain association of documents with their creator applications, you are strongly encouraged to set the Unix environment variable `APPLEPATH' to the location (directory) of your Macintosh applications. Multiple directories can be specified and are colon-separated (as with other Unix path variables). Note that NFS boundaries are not crossed during a Desktop rebuild; if you wish to include several NFS directories that are contained within one parent directory, you must specify each NFS directory individually. As mentioned above, each of these directories should also exist as static `.MIV_file' entries. For more information on the `APPLEPATH' environment variable, review Chapter 2 of the ADMINISTRATOR'S MANUAL, "Customizing MAE and Your Workstation". Example: your home directory is `/usr/ste' and your applications are installed in `/usr/ste/MacApps' and the NFS directory `/net/jaime/Applications'. You would create the static `.MIV_file' entry /net/jaime/Applications Applications and set `APPLEPATH' (using `csh' as an example) setenv APPLEPATH /usr/ste/MacApps:/net/jaime/Applications Your applications directory would then appear on the Desktop as a volume named `Applications'. Both the `MacApps' subdirectory of your home directory and the applications directory would be searched during a Desktop rebuild. ** Demo software: MAE 3.0 includes four Claris demo applications: - ClarisWorks 4.0 - FileMaker Pro 3.0 - ClarisImpact 2.0 - ClarisDraw 1.0 More information on installing the demo applications can be found in Chapter 1 of the USER'S MANUAL, "Installing the Macintosh Application Environment". You are encouraged to visit our web site at www.mae.apple.com for the latest versions of these products as well as additional demo software packages.